HAL USART initialization and configuration functions migration

The goal of this page is to show how to migrate the initialization sequence using STM32CubeMX2:

  • Open STM32CubeMX2 USART configuration panel.

  • Configure the SW layer HAL.

  • Configure the main USART features.

  • Configure the additional USART features if needed.

  • Configure the USART GPIO pins.

  • Configure the USART DMA(s) if the application requires the USART to be used in DMA mode.

  • Configure the NVIC if the application requires the USART to be used in IT mode.

  • Generate the code.

Note

The configuration below might varies from a series to another.

HAL USART configuration panel

create a new project with STM32CubeMX2, start by enabling the USART instance as Sync, as shown in this example with the selected USART1.

Project configuration panel

HAL USART main features configuration

Configure the USART main features.

USART main feature configuration

HAL USART additional features configuration

Configure the additional UART features if needed.

USART additional feature configuration

GPIO configuration

Configure the USART_CLK, USART_TX``and the ``USART_RX GPIO pins.

USART GPIO configuration

DMA configuration

Configure the DMA for data reception as needed.

USART DMA configuration

NVIC configuration

Configure the NVIC in case of an interrupt.

USART NVIC configuration

Generated USART initialization and de-initialization sequences

The USART initialization sequence is generated in the mx_usart1_hal_usart_init function in mx_usart1.c file under $YOUR_PROJECT_NAME$/$YOUR_PROJECT_NAME$_SW/generated/STM32Cube_CodeGen.

Related concepts:

STM32CubeMX2 Generated : USART initialization and De-initialization sequence

Topic

HAL1

HAL2

Handle declaration 

USART_HandleTypeDef husart1;
DMA_HandleTypeDef hLPDMA1_CH1;
DMA_HandleTypeDef hLPDMA1_CH0;

hal_usart_handle_t hUSART1;
hal_dma_handle_t hLPDMA1_CH1;
hal_dma_handle_t hLPDMA1_CH0;

Initialization and configuration sequence 

static void MX_USART1_Init(void)
{

  husart1.Instance = USART1;
  husart1.Init.BaudRate = 115200;
  husart1.Init.WordLength = USART_WORDLENGTH_8B;
  husart1.Init.StopBits = USART_STOPBITS_1;
  husart1.Init.Parity = USART_PARITY_NONE;
  husart1.Init.Mode = USART_MODE_TX_RX;
  husart1.Init.CLKPolarity = USART_POLARITY_LOW;
  husart1.Init.CLKPhase = USART_PHASE_1EDGE;
  husart1.Init.CLKLastBit = USART_LASTBIT_DISABLE;
  husart1.Init.ClockPrescaler = USART_PRESCALER_DIV1;
  husart1.SlaveMode = USART_SLAVEMODE_DISABLE;

  if (HAL_USART_Init(&husart1) != HAL_OK)
  {
    Error_Handler();
  }







  /* Fifo configuration */
  if (HAL_USARTEx_SetTxFifoThreshold(&husart1, USART_TXFIFO_THRESHOLD_1_8) != HAL_OK)
  {
    Error_Handler();
  }
  if (HAL_USARTEx_SetRxFifoThreshold(&husart1, USART_RXFIFO_THRESHOLD_1_8) != HAL_OK)
  {
    Error_Handler();
  }
  if (HAL_USARTEx_EnableFifoMode(&husart1) != HAL_OK)
  {
    Error_Handler();
  }
}

void HAL_USART_MspInit(USART_HandleTypeDef* husart)
{
  GPIO_InitTypeDef GPIO_InitStruct = {0};
  RCC_PeriphCLKInitTypeDef PeriphClkInit = {0};
  if(husart->Instance==USART1)
  {
    __HAL_RCC_USART1_CLK_ENABLE();

    PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_USART1;
    PeriphClkInit.Usart1ClockSelection = RCC_USART1CLKSOURCE_PCLK1;
    if (HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit) != HAL_OK)
    {
      Error_Handler();
    }



    /*GPIO*/
    __HAL_RCC_GPIOA_CLK_ENABLE();



    /* USART1 CK Configuration */
    GPIO_InitStruct.Pin = GPIO_PIN_8;
    GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
    GPIO_InitStruct.Pull = GPIO_NOPULL;
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
    GPIO_InitStruct.Alternate = GPIO_AF7_USART1;
    HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

    /* USART1 TX Configuration */
    GPIO_InitStruct.Pin = GPIO_PIN_12;
    GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
    GPIO_InitStruct.Pull = GPIO_NOPULL;
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
    GPIO_InitStruct.Alternate = GPIO_AF6_USART1;
    HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

    /* USART1 RX Configuration */
    GPIO_InitStruct.Pin = GPIO_PIN_1;
    GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
    GPIO_InitStruct.Pull = GPIO_NOPULL;
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
    GPIO_InitStruct.Alternate = GPIO_AF8_USART1;
    HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);


    /* Enable interrupt */
    HAL_NVIC_SetPriority(USART1_IRQn, 0, 0);
    HAL_NVIC_EnableIRQ(USART1_IRQn);


  /* Configure the DMA TX */
  __HAL_RCC_LPDMA1_CLK_ENABLE();

  hLPDMA1_CH0.Instance = LPDMA1_Channel0;
  hLPDMA1_CH0.Init.Request = LPDMA1_REQUEST_USART1_TX;
  hLPDMA1_CH0.Init.Direction = DMA_MEMORY_TO_MEMORY;
  hLPDMA1_CH0.Init.SrcInc = DMA_SINC_FIXED;
  hLPDMA1_CH0.Init.DestInc = DMA_DINC_FIXED;
  hLPDMA1_CH0.Init.SrcDataWidth = DMA_SRC_DATAWIDTH_BYTE;
  hLPDMA1_CH0.Init.DestDataWidth = DMA_DEST_DATAWIDTH_BYTE;
  hLPDMA1_CH0.Init.Priority = DMA_LOW_PRIORITY_LOW_WEIGHT;

  if (HAL_DMA_Init(&hLPDMA1_CH0) != HAL_OK)
  {
    Error_Handler();
  }






  /* Link the Transmit DMA handle to the USART handle */
  __HAL_LINKDMA(husart1, hdmarx, LPDMA1_Channel0);




  /* Enable the interruption for LPDMA1_CH0 */
  HAL_NVIC_SetPriority(LPDMA1_Channel0_IRQn, 0, 0);
  HAL_NVIC_EnableIRQ(LPDMA1_Channel0_IRQn);

 /* Configure the DMA RX */
  hLPDMA1_CH1.Instance = LPDMA1_Channel1;
  hLPDMA1_CH1.Init.Request = LPDMA1_REQUEST_USART1_RX;
  hLPDMA1_CH1.Init.Direction = DMA_MEMORY_TO_MEMORY;
  hLPDMA1_CH1.Init.SrcInc = DMA_SINC_FIXED;
  hLPDMA1_CH1.Init.DestInc = DMA_DINC_FIXED;
  hLPDMA1_CH1.Init.SrcDataWidth = DMA_SRC_DATAWIDTH_BYTE;
  hLPDMA1_CH1.Init.DestDataWidth = DMA_DEST_DATAWIDTH_BYTE;
  hLPDMA1_CH1.Init.Priority = DMA_LOW_PRIORITY_LOW_WEIGHT;

  if (HAL_DMA_Init(&hLPDMA1_CH1) != HAL_OK)
  {
    Error_Handler();
  }






  /* Link the Transmit DMA handle to the USART handle */
  __HAL_LINKDMA(husart4, hdmatx, LPDMA1_Channel1);





  HAL_NVIC_SetPriority(LPDMA1_Channel1_IRQn, 0, 0);
  HAL_NVIC_EnableIRQ(LPDMA1_Channel1_IRQn);
}

hal_usart_handle_t *mx_usart1_hal_usart_init(void)
{
  hal_usart_config_t usart_config;

  usart_config.baud_rate = 115200U;
  usart_config.clock_prescaler = HAL_USART_PRESCALER_DIV1;
  usart_config.word_length = HAL_USART_WORD_LENGTH_7_BIT;
  usart_config.stop_bits = HAL_USART_STOP_BIT_1;
  usart_config.parity = HAL_USART_PARITY_NONE;
  usart_config.direction = HAL_USART_DIRECTION_TX_RX;
  usart_config.clock_polarity = HAL_USART_CLOCK_POLARITY_LOW;
  usart_config.clock_phase = HAL_USART_CLOCK_PHASE_1_EDGE;
  usart_config.clock_last_bit = HAL_USART_CLOCK_LAST_BIT_DISABLED;
  usart_config.mode = HAL_USART_MODE_MASTER;

  /* Basic configuration */
  if (HAL_USART_Init(&hUSART1, HAL_USART1) != HAL_OK)
  {
    return NULL;
  }

  if (HAL_USART_SetConfig(&hUSART1, &usart_config) != HAL_OK)
  {
    return NULL;
  }


  /* Fifo configuration */
  if (HAL_USART_SetTxFifoThreshold(&hUSART1, HAL_USART_FIFO_THRESHOLD_1_8) != HAL_OK)
  {
    return NULL;
  }
  if (HAL_USART_SetRxFifoThreshold(&hUSART1, HAL_USART_FIFO_THRESHOLD_1_8) != HAL_OK)
  {
    return NULL;
  }
  if (HAL_USART_EnableFifoMode(&hUSART1) != HAL_OK)
  {
    return NULL;
  }








  HAL_RCC_USART1_EnableClock();



  if (HAL_RCC_USART1_SetKernelClkSource(HAL_RCC_USART1_CLK_SRC_PCLK2) != HAL_OK)
  {
    return NULL;
  }



  /* GPIO */
  HAL_RCC_GPIOA_EnableClock();

  hal_gpio_config_t  gpio_config;

  /** PA8   --------->  USART1_CK **/
  gpio_config.mode        = HAL_GPIO_MODE_ALTERNATE;
  gpio_config.output_type = HAL_GPIO_OUTPUT_PUSHPULL;
  gpio_config.pull        = HAL_GPIO_PULL_NO;
  gpio_config.speed       = HAL_GPIO_SPEED_FREQ_LOW;
  gpio_config.alternate   = HAL_GPIO_AF_7;
  HAL_GPIO_Init(HAL_GPIOA, HAL_GPIO_PIN_8 , &gpio_config);

  /** PA12  --------->  USART1_TX  **/
  gpio_config.mode        = HAL_GPIO_MODE_ALTERNATE;
  gpio_config.output_type = HAL_GPIO_OUTPUT_PUSHPULL;
  gpio_config.pull        = HAL_GPIO_PULL_NO;
  gpio_config.speed       = HAL_GPIO_SPEED_FREQ_LOW;
  gpio_config.alternate   = HAL_GPIO_AF_6;
  HAL_GPIO_Init(HAL_GPIOA, HAL_GPIO_PIN_12, &gpio_config);

  /** PA1  --------->  USART1_RX  **/
  gpio_config.mode        = HAL_GPIO_MODE_ALTERNATE;
  gpio_config.output_type = HAL_GPIO_OUTPUT_PUSHPULL;
  gpio_config.pull        = HAL_GPIO_PULL_NO;
  gpio_config.speed       = HAL_GPIO_SPEED_FREQ_LOW;
  gpio_config.alternate   = HAL_GPIO_AF_8;
  HAL_GPIO_Init(HAL_GPIOA, HAL_GPIO_PIN_1, &gpio_config);

  /* Enable interrupt */
  HAL_CORTEX_NVIC_SetPriority(USART1_IRQn, HAL_CORTEX_NVIC_PREEMP_PRIORITY_0, HAL_CORTEX_NVIC_SUB_PRIORITY_0);
  HAL_CORTEX_NVIC_EnableIRQ(USART1_IRQn);


  /* Configure the DMA TX */
  HAL_RCC_LPDMA1_EnableClock();

  hal_dma_direct_xfer_config_t xfer_cfg_usart1_tx_dma;
  xfer_cfg_usart1_tx_dma.request         = HAL_LPDMA1_REQUEST_USART1_TX;
  xfer_cfg_usart1_tx_dma.direction       = HAL_DMA_DIRECTION_MEMORY_TO_PERIPH;
  xfer_cfg_usart1_tx_dma.src_inc         = HAL_DMA_SRC_ADDR_FIXED;
  xfer_cfg_usart1_tx_dma.dest_inc        = HAL_DMA_DEST_ADDR_FIXED;
  xfer_cfg_usart1_tx_dma.src_data_width  = HAL_DMA_SRC_DATA_WIDTH_BYTE;
  xfer_cfg_usart1_tx_dma.dest_data_width = HAL_DMA_DEST_DATA_WIDTH_BYTE;
  xfer_cfg_usart1_tx_dma.priority        = HAL_DMA_PRIORITY_LOW_WEIGHT_LOW;

  if (HAL_DMA_Init(&hLPDMA1_CH0, HAL_LPDMA1_CH0) != HAL_OK)
  {
    return NULL;
  }

  if (HAL_DMA_SetConfigPeriphDirectXfer(&hLPDMA1_CH0, &xfer_cfg_usart1_tx_dma) != HAL_OK)
  {
    return NULL;
  }

  /* Link the Transmit DMA handle to the USART handle */
  if (HAL_USART_SetTxDMA(&hUSART1, &hLPDMA1_CH0) != HAL_OK)
  {
    return NULL;
  }

    /* Enable the interruption for LPDMA1_CH0 */
  HAL_CORTEX_NVIC_SetPriority(LPDMA1_CH0_IRQn, HAL_CORTEX_NVIC_PREEMP_PRIORITY_0, HAL_CORTEX_NVIC_SUB_PRIORITY_0);
  HAL_CORTEX_NVIC_EnableIRQ(LPDMA1_CH0_IRQn);

  /* Configure the DMA RX */
  hal_dma_direct_xfer_config_t xfer_cfg_usart1_rx_dma;
  xfer_cfg_usart1_rx_dma.request         = HAL_LPDMA1_REQUEST_USART1_RX;
  xfer_cfg_usart1_rx_dma.direction       = HAL_DMA_DIRECTION_PERIPH_TO_MEMORY;
  xfer_cfg_usart1_rx_dma.src_inc         = HAL_DMA_SRC_ADDR_FIXED;
  xfer_cfg_usart1_rx_dma.dest_inc        = HAL_DMA_DEST_ADDR_FIXED;
  xfer_cfg_usart1_rx_dma.src_data_width  = HAL_DMA_SRC_DATA_WIDTH_BYTE;
  xfer_cfg_usart1_rx_dma.dest_data_width = HAL_DMA_DEST_DATA_WIDTH_BYTE;
  xfer_cfg_usart1_rx_dma.priority        = HAL_DMA_PRIORITY_LOW_WEIGHT_LOW;

  if (HAL_DMA_Init(&hLPDMA1_CH1, HAL_LPDMA1_CH1) != HAL_OK)
  {
    return NULL;
  }

  if (HAL_DMA_SetConfigPeriphDirectXfer(&hLPDMA1_CH1, &xfer_cfg_usart1_rx_dma) != HAL_OK)
  {
    return NULL;
  }

  /* Link the Transmit DMA handle to the USART handle */
  if (HAL_USART_SetRxDMA(&hUSART1, &hLPDMA1_CH1) != HAL_OK)
  {
    return NULL;
  }

  /* Enable the interruption for LPDMA1_CH1 */
  HAL_CORTEX_NVIC_SetPriority(LPDMA1_CH1_IRQn, HAL_CORTEX_NVIC_PREEMP_PRIORITY_0, HAL_CORTEX_NVIC_SUB_PRIORITY_0);
  HAL_CORTEX_NVIC_EnableIRQ(LPDMA1_CH1_IRQn);

  return &hUSART1;
}

Deinitialization sequence 

void HAL_USART_MspDeInit(USART_HandleTypeDef* husart)
{
  if(husart->Instance == USART1)
  {
    /* Disable USART1 interrupt */
    HAL_NVIC_DisableIRQ(USART1_IRQn);


    /* Disable USART1 clock */
    __HAL_RCC_USART1_CLK_DISABLE();



    /* Deinitialize GPIO pins for USART1 TX,RX and CK */
    HAL_GPIO_DeInit(GPIOA, GPIO_PIN_1); // TX

    HAL_GPIO_DeInit(GPIOA, GPIO_PIN_12); // RX


    HAL_GPIO_DeInit(GPIOA, GPIO_PIN_8);  // CK

    /* De-initialize the DMA channels for RX and TX */

      HAL_DMA_DeInit(husart->hdmarx);

      HAL_DMA_DeInit(husart->hdmatx);


    /* Disable the DMA interrupts */
    HAL_NVIC_DisableIRQ(LPDMA1_Channel0_IRQn);


    HAL_NVIC_DisableIRQ(LPDMA1_Channel1_IRQn);
  }
}

void mx_usart4_hal_usart_deinit(void)
{
  /* Disable interrupt */
  HAL_CORTEX_NVIC_DisableIRQ(LPDMA1_CH1_IRQn);
  (void)HAL_USART_DeInit(&hUSART1);

  HAL_RCC_USART1_Reset();

  HAL_RCC_USART1_DisableClock();

  /* ###  GPIO pins de-initialization ################################# */
  /* Deinitialization of USART1: USART1_CK  */
  HAL_GPIO_DeInit(HAL_GPIOA, HAL_GPIO_PIN_8);

  /* ###  GPIO pins de-initialization ################################# */
  /* Deinitialization of USART1: USART1_TX  */
  HAL_GPIO_DeInit(HAL_GPIOA, HAL_GPIO_PIN_12);

  /* ###  GPIO pins de-initialization ################################# */
  /* Deinitialization of USART1: USART1_RX  */
  HAL_GPIO_DeInit(HAL_GPIOA, HAL_GPIO_PIN_1);

  /* De-initialize the DMA channel */
  HAL_DMA_DeInit(&hLPDMA1_CH0);

  /* Disable the interruption for DMA */
  HAL_CORTEX_NVIC_DisableIRQ(LPDMA1_CH0_IRQn);

  /* De-initialize the DMA channel */
  HAL_DMA_DeInit(&hLPDMA1_CH1);

  /* Disable the interruption for DMA */
  HAL_CORTEX_NVIC_DisableIRQ(LPDMA1_CH1_IRQn);

}

IRQ handle function 

void USART1_IRQHandler(void)
{
  HAL_USART_IRQHandler(&husart1);
}

void LPDMA1_CH0_IRQHandler(void)
{
  HAL_DMA_IRQHandler(&hLPDMA1_CH0);
}

void LPDMA1_CH0_IRQHandler(void)
{
  HAL_DMA_IRQHandler(&hLPDMA1_CH0);
}

void USART1_IRQHandler(void)
{
  HAL_USART_IRQHandler(&hUSART1);
}

void LPDMA1_CH0_IRQHandler(void)
{
  HAL_DMA_IRQHandler(&hLPDMA1_CH0);
}

void LPDMA1_CH0_IRQHandler(void)
{
  HAL_DMA_IRQHandler(&hLPDMA1_CH0);
}